home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 April: Mac OS SDK / Dev.CD Apr 00 SDK1.toast / Development Kits / Hardware / PC Card SDKs / PC Card Manager 3.0 / CIncludes / NameRegistry.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-06-05  |  28.5 KB  |  795 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        NameRegistry.h
  3.  
  4.      Contains:    NameRegistry Interfaces
  5.  
  6.      Version:    System 8
  7.  
  8.      DRI:        Bill Bruffey
  9.  
  10.      Copyright:    © 1984-1996 by Apple Computer, Inc.
  11.                  All rights reserved.
  12.  
  13.      Warning:    *** APPLE INTERNAL USE ONLY ***
  14.                  This file may contain unreleased API's
  15.  
  16.      BuildInfo:    Built by:            SuperMario Build Daemon
  17.                  With Interfacer:    2.0d11   (PowerPC native)
  18.                  From:                NameRegistry.i
  19.                      Revision:        34
  20.                      Dated:            3/5/96
  21.                      Last change by:    MJ
  22.                      Last comment:    Restore name lengths for backward-compatibility with Marconi.
  23.  
  24.      Bugs:        Report bugs to Radar component “System Interfaces”, “Latest”
  25.                  List the version information (from above) in the Problem Description.
  26.  
  27. */
  28. #ifndef __NAMEREGISTRY__
  29. #define __NAMEREGISTRY__
  30.  
  31. #ifndef __TYPES__
  32. #include <Types.h>
  33. #endif
  34.  
  35. #ifdef __cplusplus
  36. extern "C" {
  37. #endif
  38.  
  39. #if PRAGMA_IMPORT_SUPPORTED
  40. #pragma import on
  41. #endif
  42.  
  43. #if PRAGMA_ALIGN_SUPPORTED
  44. #pragma options align=power
  45. /* the following contents can only be used by compilers that support PowerPC struct alignment */
  46.  
  47. #if FOR_SYSTEM7_AND_SYSTEM8_PREEMPTIVE
  48. /*
  49.  These definitions apply to both the System7 and System8 interfaces
  50.  RegEntryRef:    The Global Entry Reference
  51. */
  52. struct RegEntryRef {
  53.     UInt32                             contents[4];
  54. };
  55. typedef struct RegEntryRef RegEntryRef;
  56.  
  57.  
  58. enum {
  59.     kRegPathNameSeparator        = ':'                            /* 0x3A */
  60. };
  61.  
  62.  
  63. enum {
  64.     kRegMaxPropertyNameLength    = 31                            /* Max length of Property Name (terminator not included) */
  65. };
  66.  
  67. typedef char RegPropertyNameBuf[32];
  68. #endif
  69. #if FOR_SYSTEM8_PREEMPTIVE
  70. /*
  71. ------------------------------------------------------------------------------------
  72. Name Registry Interface for System 8
  73. ------------------------------------------------------------------------------------
  74. */
  75. /*
  76. ------------------------------------------------------------------------------------
  77.  Foundation Types
  78. ------------------------------------------------------------------------------------
  79. */
  80. /* Entry Name Definitions (Entry Names are C-Strings)*/
  81.  
  82. enum {
  83.     kRegMaxEntryNameLength        = 47                            /* Max length of a C-String Entry Name (terminator not included) */
  84. };
  85.  
  86. /* length of RegEntryNameBuf = kRegMaxEntryNameLength +1*/
  87. typedef char RegEntryNameBuf[48];
  88. /* Create Entry Options*/
  89. typedef OptionBits RegCreateEntryOptions;
  90. /* use "kNilOptions" for no options*/
  91.  
  92. enum {
  93.     kRegCreateResidentEntry        = 0x00000001                    /* make entry resident */
  94. };
  95.  
  96. /* Delete Entry Options*/
  97. typedef OptionBits RegDeleteEntryOptions;
  98. /* use "kNilOptions" for no options*/
  99.  
  100. enum {
  101.     kRegDeleteEmbeddedEntries    = 0x00000001                    /* delete embedded entries */
  102. };
  103.  
  104. /* Entry Iterator*/
  105. typedef struct OpaqueRegEntryIterator* RegEntryIterator;
  106. /* Entry Iterator Options*/
  107. typedef OptionBits RegEntryIteratorOptions;
  108. /* use "kNilOptions" for no options*/
  109.  
  110. enum {
  111.     kRegIterateEmbeddedEntries    = 0x00000002                    /* iterate embedded entries */
  112. };
  113.  
  114. /*
  115.  Property Instances
  116.  An instance value for a property is assigned by the Name Registry when the
  117.  instance is created.  This value is used to distinguish this instance from any
  118.  other instances of the property.  Instance values are unique and persistent for
  119.  the life of the property. Thus, clients can obtain a reference to a property (name
  120.  and instance value) and use that reference until the property is deleted or the
  121.  system is restarted.  At restart, new instance values are assigned to all
  122.  properties, including any restored persistent properties.
  123. */
  124. typedef UInt32 RegPropertyInstance;
  125.  
  126. enum {
  127.     kRegNilPropertyInstance        = 0x00000000,                    /* nil property instance */
  128.     kRegAnyPropertyInstance        = 0xFFFFFFFF,                    /* any property instance */
  129.     kRegAllPropertyInstances    = 0xFFFFFFFE                    /* all property instances */
  130. };
  131.  
  132. /* Create Property Options*/
  133. typedef OptionBits RegCreatePropertyOptions;
  134. /* use "kNilOptions" for no options*/
  135.  
  136. enum {
  137.     kRegMultiInstanceProperty    = 0x00000001                    /* multiple-instance property */
  138. };
  139.  
  140. /* Property Iterator*/
  141. typedef struct OpaqueRegPropertyIterator* RegPropertyIterator;
  142. /* Transaction Reference*/
  143. typedef struct OpaqueRegTransaction* RegTransaction;
  144. /* Nil Transaction Reference*/
  145. #define kRegNilTransaction    (RegTransaction)0
  146. /*
  147. ------------------------------------------------------------------------------------
  148.  Name Registry Calls
  149. ------------------------------------------------------------------------------------
  150. */
  151. /*
  152. ------------------------------------------------------------------------------------
  153.  EntryRef Handling
  154. ------------------------------------------------------------------------------------
  155. */
  156. /* Compare two EntryRef's for equality. */
  157. extern Boolean RegEntryRefIsEqual(const RegEntryRef *ref1, const RegEntryRef *ref2);
  158.  
  159. /*
  160. ------------------------------------------------------------------------------------
  161.  Adding and Deleting Entries
  162. ------------------------------------------------------------------------------------
  163. */
  164. /*
  165.  Create an Entry
  166.  If (parentEntry) is NULL, the path name is assumed to be an absolute path name
  167.  rooted to the anonymous, unnamed root.  
  168.  Note, RegCreateEntry only creates a single entry, the one at the end of the path.
  169.  Thus, all parent entries along the path to the new entry (ancestors) must already
  170.  exist.
  171. */
  172. extern OSStatus RegCreateEntry(RegTransaction transaction, const RegEntryRef *parentEntry, const char *pathName, RegCreateEntryOptions options, RegEntryRef *newEntry);
  173.  
  174. /*
  175.  Delete an Entry or Subtree
  176.  RegDeleteEntry can be used to delete a single entry or a complete subtree.
  177.  To delete a subtree, set the RegDeleteEmbedded option.
  178.  All properties for deleted entries are also deleted.
  179. */
  180. extern OSStatus RegDeleteEntry(RegTransaction transaction, const RegEntryRef *ref, RegDeleteEntryOptions options);
  181.  
  182. /*
  183. ------------------------------------------------------------------------------------
  184.  LookUp Entry by Name
  185. ------------------------------------------------------------------------------------
  186. */
  187. /*
  188.  Lookup Entry
  189.  Locates an entry given a specified subroot (searchPointRef) and path name.  If the
  190.  searchPointRef pointer is NULL, the path name is assumed to be an absolute path
  191.  name rooted to the root of the Registry.
  192. */
  193. extern OSStatus RegLookupEntry(RegTransaction transaction, const RegEntryRef *searchPointRef, const char *pathName, RegEntryRef *foundEntry);
  194.  
  195. /*
  196. ------------------------------------------------------------------------------------
  197. Get Entry Name and Parent
  198. ------------------------------------------------------------------------------------
  199. */
  200. /*
  201.  Retrieve the name component for the specified entry, and return the EntryRef for
  202.  the parent entry.
  203. */
  204. extern OSStatus RegGetEntryName(RegTransaction transaction, const RegEntryRef *entryRef, RegEntryRef *parentEntry, char *nameComponent);
  205.  
  206. /*
  207. ------------------------------------------------------------------------------------
  208. Get Path Name
  209. ------------------------------------------------------------------------------------
  210. */
  211. /*
  212.  These are utility routines to turn an Entry ID back into a name string.
  213.  Get Entry Path Size
  214.  Note, path size is returned in bytes for C-String paths
  215. */
  216. extern OSStatus RegGetEntryPathSize(RegTransaction transaction, const RegEntryRef *entryRef, ByteCount *pathSize);
  217.  
  218. /* Get Path Name*/
  219. extern OSStatus RegGetEntryPath(RegTransaction transaction, const RegEntryRef *entryRef, char *pathName, ByteCount pathSize);
  220.  
  221. /*
  222. ------------------------------------------------------------------------------------
  223.  Entry Iteration
  224. ------------------------------------------------------------------------------------
  225. */
  226. /*
  227.  An Entry Iterator maintains three variables that are of interest to clients.
  228.  First is an "OutermostScope" which defines the outer boundry of the iteration.
  229.  This is defined by the starting entry and includes that entry plus all of it's
  230.  embedded entries. Second is a "currentScope" which is the entry the iterator is
  231.  currently in. And third is a "currentPosition" which is the last entry returned
  232.  during an iteration.
  233.  Create Entry Iterator
  234.  Create the iterator structure. The outermostScope and currentScope of the iterator
  235.  are set to "startEntry".  If "startEntry" = NULL, the outermostScope and
  236.  currentScope are set to the root entry.  The currentPosition for the iterator is
  237.  set to "nil".
  238.  If propertyName != Null, propertyName, propertyValue, and propertySize are used
  239.  to filter the entries returned during an iteration.  If propertyName == Null, all
  240.  entries are returned.
  241. */
  242. extern OSStatus RegCreateEntryIterator(RegTransaction transaction, const RegEntryRef *startEntry, RegEntryIteratorOptions options, const char *propertyName, const void *propertyValue, ByteCount propertySize, RegEntryIterator *iterator);
  243.  
  244. /* Dispose Entry Iterator*/
  245. extern OSStatus RegDisposeEntryIterator(RegEntryIterator iterator);
  246.  
  247. /*
  248.  Enter Child Entry
  249.  Move an Entry Iterator into the scope of a specified child entry.  The
  250.  currentScope of the iterator is set to the entry specified in "childEntry".  If
  251.  "childEntry" is nil, the currentScope is set to the entry specified by the
  252.  currentPosition of the iterator.
  253.  Note RegEnterEntry cannot be used if the "kRegIterateEmbeddedEntries" option was
  254.  set when the iterator was created. 
  255. */
  256. extern OSStatus RegEnterEntry(RegTransaction transaction, RegEntryIterator iterator, RegEntryRef *childEntry);
  257.  
  258. /*
  259.  Exit to Parent Entry
  260.  Move an Entry Iterator out of the current entry back into the scope of it's parent
  261.  entry. The currentPosition of the iterator is reset to the current entry (the
  262.  previous currentScope), so the next iteration call will continue where it left off.
  263.  This position is returned in parameter "currentPosition".
  264.  Note RegExitEntry cannot be used if the "kRegIterateEmbeddedEntries" option was
  265.  set when the iterator was created. 
  266. */
  267. extern OSStatus RegExitEntry(RegTransaction transaction, RegEntryIterator iterator, RegEntryRef *currentPosition);
  268.  
  269. /*
  270.  Iterate Entries 
  271.  Iterate and return entries contained within the entry defined by the current
  272.  scope of the iterator. If kRegIterateEmbeddedEntries option was specified when the
  273.  iterator was created, all embedded entries will be included in the iteration.  If a
  274.  property selection (name , value, and size) was specified when the iterator was
  275.  created, the only entries having a matching property are returned.  Entries are
  276.  returned one at a time. When OSStatus == nrIterationDone, all entries have been exhausted, and the
  277.  value of nextEntry will be Nil. If changed == true, one or more changes (entry
  278.  create or delete) occured since the last interation call.
  279. */
  280. extern OSStatus RegIterateEntries(RegTransaction transaction, RegEntryIterator iterator, RegEntryRef *nextEntry, Boolean *changed);
  281.  
  282. /*
  283.  Restart Entry Iteration
  284.  Restart an iteration within the current scope.  The iterator is reset such that
  285.  iteration of the contents of the currentScope entry can be restarted. The
  286.  outermostScope and currentScope of the iterator are unchanged. The currentPosition
  287.  for the iterator is set to "nil".
  288. */
  289. extern OSStatus RegRestartEntryIteration(RegEntryIterator iterator);
  290.  
  291. /*
  292. ------------------------------------------------------------------------------------
  293.  Adding and Deleting Properties
  294. ------------------------------------------------------------------------------------
  295. */
  296. /*
  297.  Create Property
  298.  A  single instance property is created by default. To create a multiple-instance
  299.  property set the kRegMultiInstanceProperty option. The next instance of the
  300.  property will be created and the instance value will be returned in
  301.  propertyInstance.
  302. */
  303. extern OSStatus RegCreateProperty(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, const void *propertyValue, ByteCount propertySize, RegCreatePropertyOptions options, RegPropertyInstance *propertyInstance);
  304.  
  305. /*
  306.  Delete Property
  307.  To delete a property the desired property instance(s) must be explicitly
  308.  identified. To delete a single instance property set propertyInstance to
  309.  kRegNilPropertyInstance.  To delete all instances of a multi-instance property, set
  310.  propertyInstance to kRegAllPropertyInstances.  Otherwise, propertyInstance must
  311.  be set to a valid instance value.
  312. */
  313. extern OSStatus RegDeleteProperty(RegTransaction transaction, const RegEntryRef *EntryRef, const char *propertyName, RegPropertyInstance propertyInstance);
  314.  
  315. /*
  316. ------------------------------------------------------------------------------------
  317.  Get/Set Property Values
  318. ------------------------------------------------------------------------------------
  319. */
  320. /*
  321.  Get/Set the value of the specified property for the specified entry.  To get, get
  322.  size, and set property values the desired property instance must be explicitly
  323.  identified.  For single instance properites propertyInstance must  be set to
  324.  kRegNilPropertyInstance.  Otherwise, propertyInstance must be set to a valid
  325.  instance value.
  326.  Get Property size
  327. */
  328. extern OSStatus RegGetPropertySize(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyInstance propertyInstance, ByteCount *propertySize);
  329.  
  330. /* Get Property*/
  331. extern OSStatus RegGetProperty(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyInstance propertyInstance, void *propertyValue, ByteCount *propertySize);
  332.  
  333. /* Set Property*/
  334. extern OSStatus RegSetProperty(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyInstance propertyInstance, const void *propertyValue, ByteCount propertySize);
  335.  
  336. /*
  337. ------------------------------------------------------------------------------------
  338.  Iterating Properties
  339. ------------------------------------------------------------------------------------
  340. */
  341. /*
  342.  Create Property Iterator
  343.  Create the property iterator structure. The target entry is defined by entryRef.
  344.  If a propertyName is specified, only property instances having the specified name
  345.  are returned. If propertyName == nil, all properties are returned.
  346. */
  347. extern OSStatus RegCreatePropertyIterator(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyIterator *iterator);
  348.  
  349. /* Dispose Property Iterator*/
  350. extern OSStatus RegDisposePropertyIterator(RegPropertyIterator iterator);
  351.  
  352. /*
  353.  Iterate Properites
  354.  Iterate and return properties for given entry.  If a propertyName was specified
  355.  when the iterator was created, then only property instances for that name are
  356.  returned. Otherwise, all properties are returned.  The return value in
  357.  propertyInstance will be kRegNilPropertyInstance if the property is single
  358.  instance.  Else it will contain the instance value for the property. If
  359.  changed == true, one or more changes (property creates or deletes) occured since the
  360.  last iterate call.  When OSStatus == nrIterationDone, all properties have been exhausted.
  361. */
  362. extern OSStatus RegIterateProperties(RegTransaction transaction, RegPropertyIterator iterator, char *foundProperty, RegPropertyInstance *propertyInstance, Boolean *changed);
  363.  
  364. /*
  365.  Restart Property Iteration
  366.  Used to re-iterate over a list of properties.  The Property Iterator is reset to
  367.  the beginning of the list of properties for an entry.
  368. */
  369. extern OSStatus RegRestartPropertyIteration(RegPropertyIterator iterator);
  370.  
  371. /*
  372. ------------------------------------------------------------------------------------
  373.  Transaction-control calls
  374. ------------------------------------------------------------------------------------
  375. */
  376. /*
  377.  Begin Transaction
  378.  Marks the beginning of a sequence of Name Registry calls that compose a Registry
  379.  transaction.  An internal data structure for the transaction is created and a
  380.  reference to the transaction is returned in "tranasaction". This reference must be
  381.  used with all subsequence Name Registry calls pertaining to the transaction. The
  382.  transaction reference must be disposed using a RegCommitTransaction or
  383.  RegAbortTranscation call.    
  384. */
  385. extern OSStatus RegBeginTransaction(RegTransaction *transaction);
  386.  
  387. /*
  388.  Commit Transaction
  389.  Commits the changes made to the registry for a sepecified transaction. All changes
  390.  (entry create/delete, property create/delete, and  property value update) made for
  391.  the transaction are atomically integrated into the Registry.  If result ==
  392.  nrTransactionAborted, there was a conflict with changes from some other transaction,
  393.  and this transaction was aborted, i.e., no changes for this transaction were made.
  394.  In this case the transaction should be repeated.
  395.  Note that RegCommitTransaction always disposes the transcation reference
  396.  independant of the outcome of the transaction.  So to repeat a transaaction you
  397.  must start over with a RegBeginTransaction call.
  398. */
  399. extern OSStatus RegCommitTransaction(RegTransaction transaction);
  400.  
  401. /*
  402.  Abort Transaction
  403.  Aborts the changes made to the registry for a sepecified transaction. All changes
  404.  (entry create/delete, property create/delete, and  property value update) made for
  405.  the transaction are disgarded.  
  406.  RegAbortTransaction also disposes of the transcation reference.
  407. */
  408. extern OSStatus RegAbortTransaction(RegTransaction transaction);
  409.  
  410. #endif
  411. #if FOR_SYSTEM7_AND_SYSTEM8_DEPRECATED
  412. /*
  413. ------------------------------------------------------------------------------------
  414.     Name Registry Interface for PowerSurge 1.0.2
  415. ------------------------------------------------------------------------------------
  416. */
  417. /*
  418.  * Name Registry - API for device driver name registration
  419.  *
  420.  * This interface provides access to the namespace used
  421.  * by device drivers.  The data structures and entry points
  422.  * are specialized and simplified for device driver use.
  423. */
  424. /*
  425.  //////////////////////////////////////////////////////////////////////////////
  426. //
  427. // Data Structures
  428. //
  429. */
  430. /*
  431.  //////////////////////////////////////////////////////////////////////////////
  432. // 
  433. // Foundation Types
  434. //
  435. */
  436. /* Value of a property */
  437. typedef void *RegPropertyValue;
  438. /* Length of property value */
  439. typedef UInt32 RegPropertyValueSize;
  440. /*
  441.  //////////////////////////////////////////////////////////////////////////////
  442. // 
  443. // RegEntryID    :    The Global x-Namespace Entry Identifier
  444. //
  445. */
  446. /* RegEntryID:    The Global Entry ID*/
  447. typedef RegEntryRef RegEntryID;
  448. typedef RegEntryID *RegEntryIDPtr;
  449. /*
  450.  //////////////////////////////////////////////////////////////////////////////
  451. //
  452. // Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  453. //
  454. //    * Names are a colon-separated list of name components.  Name components
  455. //      may not themselves contain colons.  
  456. //    * Names are presented as null-terminated ASCII character strings.
  457. //    * Names follow similar parsing rules to Apple file system absolute
  458. //      and relative paths.  However the '::' parent directory syntax is
  459. //      not currently supported.
  460. */
  461. /* Max length of Entry Name */
  462.  
  463. enum {
  464.     kRegCStrMaxEntryNameLength    = 47
  465. };
  466.  
  467. /* Entry Names are single byte ASCII */
  468. typedef char RegCStrEntryName;
  469. typedef char *RegCStrEntryNamePtr;
  470. /* length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1*/
  471. typedef char RegCStrEntryNameBuf[48];
  472. typedef char RegCStrPathName;
  473. typedef UInt32 RegPathNameSize;
  474.  
  475. enum {
  476.     kRegEntryNameTerminator        = 0x00,                            /* '\0' */
  477.     kRegPathNameTerminator        = 0x00                            /* '\0' */
  478. };
  479.  
  480. /*
  481.  //////////////////////////////////////////////////////////////////////////////
  482. //
  483. // Property Name and ID Definitions
  484. //    (Applies to all Properties Regardless of NameSpace)
  485. */
  486.  
  487. enum {
  488.     kRegMaximumPropertyNameLength = 31,                            /* Max length of Property Name */
  489.     kRegPropertyNameTerminator    = 0x00                            /* '\0' */
  490. };
  491.  
  492. typedef char RegPropertyName;
  493. typedef char *RegPropertyNamePtr;
  494. /*
  495.  //////////////////////////////////////////////////////////////////////////////
  496. //
  497. // Iteration Operations
  498. //
  499. //    These specify direction when traversing the name relationships
  500. */
  501. typedef UInt32 RegIterationOp;
  502. typedef RegIterationOp RegEntryIterationOp;
  503.  
  504. enum {
  505.                                                                 /* Absolute locations*/
  506.     kRegIterRoot                = 0x00000002,                    /* "Upward" Relationships    */
  507.     kRegIterParents                = 0x00000003,                    /* include all  parent(s) of entry */
  508.                                                                 /* "Downward" Relationships*/
  509.     kRegIterChildren            = 0x00000004,                    /* include all children */
  510.     kRegIterSubTrees            = 0x00000005,                    /* include all sub trees of entry */
  511.     kRegIterDescendants            = 0x00000005,                    /* include all descendants of entry */
  512.                                                                 /* "Horizontal" Relationships    */
  513.     kRegIterSibling                = 0x00000006,                    /* include all siblings */
  514.                                                                 /* Keep doing the same thing*/
  515.     kRegIterContinue            = 0x00000001
  516. };
  517.  
  518. /*
  519.  //////////////////////////////////////////////////////////////////////////////
  520. //
  521. // Name Entry and Property Modifiers
  522. //
  523.  
  524. //
  525. // Modifiers describe special characteristics of names
  526. // and properties.  Modifiers might be supported for
  527. // some names and not others.
  528. // 
  529. // Device Drivers should not rely on functionality
  530. // specified as a modifier.
  531. */
  532. typedef UInt32 RegModifiers;
  533. typedef RegModifiers RegEntryModifiers;
  534. typedef RegModifiers RegPropertyModifiers;
  535.  
  536. enum {
  537.     kRegNoModifiers                = 0x00000000,                    /* no entry modifiers in place */
  538.     kRegUniversalModifierMask    = 0x0000FFFF,                    /* mods to all entries */
  539.     kRegNameSpaceModifierMask    = 0x00FF0000,                    /* mods to all entries within namespace */
  540.     kRegModifierMask            = 0xFF000000                    /* mods to just this entry */
  541. };
  542.  
  543. /* Universal Property Modifiers */
  544.  
  545. enum {
  546.     kRegPropertyValueIsSavedToNVRAM = 0x00000020,                /* property is non-volatile (saved in NVRAM) */
  547.     kRegPropertyValueIsSavedToDisk = 0x00000040                    /* property is non-volatile (saved on disk) */
  548. };
  549.  
  550. /*
  551.  ///////////////////////
  552. //
  553. // The Registry API
  554. //
  555. /////////////////////// 
  556. */
  557. /*
  558.  ///////////////////////
  559. //
  560. // Entry Management
  561. //
  562. /////////////////////// 
  563. */
  564. /*
  565. -------------------------------
  566.  * EntryID handling
  567. */
  568. /*
  569.  * Initialize an EntryID to a known invalid state
  570.  *   note: invalid != uninitialized
  571. */
  572. extern OSStatus RegistryEntryIDInit(RegEntryID *id);
  573.  
  574. /*
  575.  * Compare EntryID's for equality or if invalid
  576.  *
  577.  * If a NULL value is given for either id1 or id2, the other id 
  578.  * is compared with an invalid ID.  If both are NULL, the id's 
  579.  * are consided equal (result = true). 
  580. */
  581. extern Boolean RegistryEntryIDCompare(const RegEntryID *id1, const RegEntryID *id2);
  582.  
  583. /*
  584.  * Copy an EntryID
  585. */
  586. extern OSStatus RegistryEntryIDCopy(const RegEntryID *src, RegEntryID *dst);
  587.  
  588. /*
  589.  * Free an ID so it can be reused.
  590. */
  591. extern OSStatus RegistryEntryIDDispose(RegEntryID *id);
  592.  
  593. /*
  594. -------------------------------
  595.  * Adding and removing entries
  596.  *
  597.  * If (parentEntry) is NULL, the name is assumed
  598.  * to be a rooted path. It is rooted to an anonymous, unnamed root.
  599. */
  600. extern OSStatus RegistryCStrEntryCreate(const RegEntryID *parentEntry, const RegCStrPathName *name, RegEntryID *newEntry);
  601.  
  602. extern OSStatus RegistryEntryDelete(const RegEntryID *id);
  603.  
  604. /*
  605. ---------------------------
  606.  * Traversing the namespace
  607.  *
  608.  * To support arbitrary namespace implementations in the future,
  609.  * I have hidden the form that the place pointer takes.  The previous
  610.  * interface exposed the place pointer by specifying it as a
  611.  * RegEntryID.
  612.  *
  613.  * I have also removed any notion of returning the entries
  614.  * in a particular order, because an implementation might
  615.  * return the names in semi-random order.  Many name service
  616.  * implementations will store the names in a hashed lookup
  617.  * table.
  618.  *
  619.  * Writing code to traverse some set of names consists of
  620.  * a call to begin the iteration, the iteration loop, and
  621.  * a call to end the iteration.  The begin call initializes
  622.  * the iteration cookie data structure.  The call to end the 
  623.  * iteration should be called even in the case of error so 
  624.  * that allocated data structures can be freed.
  625.  *
  626.  *    Create(...)
  627.  *    do {
  628.  *        Iterate(...);
  629.  *    } while (!done);
  630.  *    Dispose(...);
  631.  *
  632.  * This is the basic code structure for callers of the iteration
  633.  * interface.
  634. */
  635. typedef struct OpaqueRegEntryIter* RegEntryIter;
  636. /*
  637.  * create/dispose the iterator structure
  638.  *   defaults to root with relationship = kRegIterDescendants
  639. */
  640. extern OSStatus RegistryEntryIterateCreate(RegEntryIter *cookie);
  641.  
  642. extern OSStatus RegistryEntryIterateDispose(RegEntryIter *cookie);
  643.  
  644. /*
  645.  * set Entry Iterator to specified entry
  646. */
  647. extern OSStatus RegistryEntryIterateSet(RegEntryIter *cookie, const RegEntryID *startEntryID);
  648.  
  649. /*
  650.  * Return each value of the iteration
  651.  *
  652.  * return entries related to the current entry
  653.  * with the specified relationship
  654. */
  655. extern OSStatus RegistryEntryIterate(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done);
  656.  
  657. /*
  658.  * return entries with the specified property
  659.  *
  660.  * A NULL RegPropertyValue pointer will return an
  661.  * entry with the property containing any value.
  662. */
  663. extern OSStatus RegistryEntrySearch(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize);
  664.  
  665. /*
  666. --------------------------------
  667.  * Find a name in the namespace
  668.  *
  669.  * This is the fast lookup mechanism.
  670.  * NOTE:  A reverse lookup mechanism
  671.  *      has not been provided because
  672.  *        some name services may not
  673.  *        provide a fast, general reverse
  674.  *        lookup.
  675. */
  676. extern OSStatus RegistryCStrEntryLookup(const RegEntryID *searchPointID, const RegCStrPathName *pathName, RegEntryID *foundEntry);
  677.  
  678. /*
  679. ---------------------------------------------
  680.  * Convert an entry to a rooted name string
  681.  *
  682.  * A utility routine to turn an Entry ID
  683.  * back into a name string.
  684. */
  685. extern OSStatus RegistryEntryToPathSize(const RegEntryID *entryID, RegPathNameSize *pathSize);
  686.  
  687. extern OSStatus RegistryCStrEntryToPath(const RegEntryID *entryID, RegCStrPathName *pathName, RegPathNameSize pathSize);
  688.  
  689. /*
  690.  * Parse a path name.
  691.  *
  692.  * Retrieve the last component of the path, and
  693.  * return a spec for the parent.
  694. */
  695. extern OSStatus RegistryCStrEntryToName(const RegEntryID *entryID, RegEntryID *parentEntry, RegCStrEntryName *nameComponent, Boolean *done);
  696.  
  697. /*
  698.  //////////////////////////////////////////////////////
  699. //
  700. // Property Management
  701. //
  702. ////////////////////////////////////////////////////// 
  703. */
  704. /*
  705. -------------------------------
  706.  * Adding and removing properties
  707. */
  708. extern OSStatus RegistryPropertyCreate(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize);
  709.  
  710. extern OSStatus RegistryPropertyDelete(const RegEntryID *entryID, const RegPropertyName *propertyName);
  711.  
  712. /*
  713. ---------------------------
  714.  * Traversing the Properties of a name
  715.  *
  716. */
  717. typedef struct OpaqueRegPropertyIter* RegPropertyIter;
  718. extern OSStatus RegistryPropertyIterateCreate(const RegEntryID *entry, RegPropertyIter *cookie);
  719.  
  720. extern OSStatus RegistryPropertyIterateDispose(RegPropertyIter *cookie);
  721.  
  722. extern OSStatus RegistryPropertyIterate(RegPropertyIter *cookie, RegPropertyName *foundProperty, Boolean *done);
  723.  
  724. /*
  725.  * Get the value of the specified property for the specified entry.
  726.  *
  727. */
  728. extern OSStatus RegistryPropertyGetSize(const RegEntryID *entryID, const RegPropertyName *propertyName, RegPropertyValueSize *propertySize);
  729.  
  730. /*
  731.  * (*propertySize) is the maximum size of the value returned in the buffer
  732.  * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  733.  * value returned.
  734. */
  735. extern OSStatus RegistryPropertyGet(const RegEntryID *entryID, const RegPropertyName *propertyName, void *propertyValue, RegPropertyValueSize *propertySize);
  736.  
  737. extern OSStatus RegistryPropertySet(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize);
  738.  
  739. /*
  740.  //////////////////////////////////////////////////////
  741. //
  742. // Modibute (err, I mean Modifier) Management
  743. //
  744. ////////////////////////////////////////////////////// 
  745. */
  746. /*
  747.  * Modifiers describe special characteristics of names
  748.  * and properties.  Modifiers might be supported for
  749.  * some names and not others.
  750.  * 
  751.  * Device Drivers should not rely on functionality
  752.  * specified as a modifier.  These interfaces
  753.  * are for use in writing Experts.
  754. */
  755. /*
  756.  * Get and Set operators for entry modifiers
  757. */
  758. extern OSStatus RegistryEntryGetMod(const RegEntryID *entry, RegEntryModifiers *modifiers);
  759.  
  760. extern OSStatus RegistryEntrySetMod(const RegEntryID *entry, RegEntryModifiers modifiers);
  761.  
  762. /*
  763.  * Get and Set operators for property modifiers
  764. */
  765. extern OSStatus RegistryPropertyGetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers *modifiers);
  766.  
  767. extern OSStatus RegistryPropertySetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers modifiers);
  768.  
  769. /*
  770.  * Iterator operator for entry modifier search
  771. */
  772. extern OSStatus RegistryEntryMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegEntryModifiers matchingModifiers);
  773.  
  774. /*
  775.  * Iterator operator for entries with matching 
  776.  * property modifiers
  777. */
  778. extern OSStatus RegistryEntryPropertyMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegPropertyModifiers matchingModifiers);
  779.  
  780. #endif
  781.  
  782. #pragma options align=reset
  783. #endif /* PRAGMA_ALIGN_SUPPORTED */
  784.  
  785. #if PRAGMA_IMPORT_SUPPORTED
  786. #pragma import off
  787. #endif
  788.  
  789. #ifdef __cplusplus
  790. }
  791. #endif
  792.  
  793. #endif /* __NAMEREGISTRY__ */
  794.  
  795.